<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>
  File: API
  
    &mdash; Ruby China API 文档
  
</title>

  <link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />

  <link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />

<script type="text/javascript" charset="utf-8">
  pathId = "API";
  relpath = '';
</script>


  <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>

  <script type="text/javascript" charset="utf-8" src="js/app.js"></script>


  </head>
  <body>
    <div class="nav_wrap">
      <iframe id="nav" src="class_list.html"></iframe>
      <div id="resizer"></div>
    </div>

    <div id="main" tabindex="-1">
      <div id="header">
        <div id="menu">
  
    <a href="_index.html">Index</a> &raquo; 
    <span class="title">File: API</span>
  
</div>

        <div id="search">
  
    <a class="full_list_link" id="class_list_link"
        href="class_list.html">

        <svg width="24" height="24">
          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
        </svg>
    </a>
  
</div>
        <div class="clear"></div>
      </div>

      <iframe id="search_frame" src="class_list.html"></iframe>

      <div id="content"><div id='filecontents'><h1>API 文档</h1>

<h2>OAuth 2 / API 认证</h2>

<p>在使用 API 之前，你需要 <a href="/oauth/applications/new">注册应用</a> 并获得可以 <strong>OAuth App</strong> 信息。并使用标准的 OAuth 2 实现登录，获得 <code>access_token</code> 信息。</p>

<h3>OAuth 路径</h3>

<ul>
<li>/oauth/authorize</li>
<li>/oauth/token</li>
<li>/oauth/revoke</li>
</ul>

<h3>Response 说明</h3>

<p>所有 Response 采用 JSON 格式返回，请求状态通过 HTTP Status 返回。</p>

<h3>HTTP Status</h3>

<p>错误的情况 Response Body 一定会是这样的格式: <code>{ &quot;error&quot; : &quot;Error message&quot; }</code></p>

<ul>
<li>200, 201 - 请求成功，或执行成功。</li>
<li>400 - 参数不符合 API 的要求、或者数据格式验证没有通过，请配合 Response Body 里面的 error 信息确定问题。</li>
<li>401 - 用户认证失败，或缺少认证信息，比如 access_token 过期，或没传，可以尝试用 refresh_token 方式获得新的 access_token。</li>
<li>403 - 当前用户对资源没有操作权限。</li>
<li>404 - 资源不存在。</li>
<li>500 - 服务器异常。</li>
</ul>

<h4>资源权限描述</h4>

<p>在部分 API 的 response 内容里面你会看到 <code>abilities</code> 节点，这是特别标识当前 <code>access_token</code> 对应的用户对此资源的权限。</p>

<p>请参考源代码，确定那些路径是需要用户认证的，需要用户认证的路径，你需要带上 <code>access_token=?</code> 参数。</p>

<p><strong>例如</strong></p>

<pre class="code json"><code class="json">{
  &quot;topic&quot;: {
    &quot;id&quot;: 256170,
    ....,
    &quot;abilities&quot;: { &quot;update&quot;: true, &quot;destroy&quot;: true }
  }
}
</code></pre>

<ul>
<li>update 是否有权限修改</li>
<li>destroy 是否有权限删除</li>
</ul>

<h2>API 路由</h2>

<p>API 的详细文档，请访问 <a href="/api-doc/Api/V3.html">Api::V3</a> 阅读。</p>

<h2>演示</h2>

<p>我们用 Ruby 演示一下访问 <a href="/api-doc/Api/V3/RootController.html#hello-instance_method">/api/v3/hello.json</a> 这个路径，其中包含 OAuth 2 的流程。</p>

<p><em>这里用到 RubyGem <a href="https://github.com/intridea/oauth2">oauth2</a></em></p>

<pre class="code rb"><code class="rb">require &quot;oauth2&quot;
client = OAuth2::Client.new(&#39;client id&#39;, &#39;secret&#39;, site: &#39;https://ruby-china.org&#39;)
access_token = client.password.get_token(&#39;username&#39;, &#39;password&#39;)
res = Faraday.get(&quot;https://ruby-china.org/api/v3/hello.json?access_token=#{access_token.token}&quot;)
puts res.status
puts res.body
</code></pre>

<p>最后输出</p>

<pre class="code rb"><code class="rb">{ &#39;current_user&#39; : &#39;username&#39; }
</code></pre>
</div></div>

      <div id="footer">
  Generated on Thu Oct 20 19:35:15 2016 by
  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
  0.9.5 (ruby-2.3.1).
</div>

    </div>
  </body>
</html>